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INTRODUCTION 


The GREDIT.B file contains a simplified graphics editor program written in MTU 
BASIC and uses the CIL and IGL Libraries. This program is designed to serve two 
purposes. First, it is intended to provide examples of how to use the IGL and CIL 
Libraries in an actual application program. Second, it is intended to be a used as 
a program for creating, editing, and saving graphics images using a simple graphics 
data base. 


STARTUP 


To start up the program, simply enter MTU BASIC with a BASIC command and then 
execute the command: 


RUN "GREDIT" 


The program will "LIB" in the CIL and IGL Libraries itself, so the disk in drive 0 
must contain these libraries. 


GENERAL DESCRIPTION 


The GREDIT Program is a menu driven application program. It uses the legend 
boxes as the menus and the function keys as the means of selection. In the next 
section, descriptions of the various menus and the function of each selection are 
given. 


The function of the GREDIT program is to provide a simple graphics editor. It 
allows you to create and edit a graphics image. Where a word processor allows you 
to edit words, the GREDIT program allows you to edit lines in an image. 


The image manipulated by the GREDIT program will consist of lines and charac- 
ters. The lines and characters to be drawn will be specified by you when you enter 
or edit the image. The program records where the lines and characters are posi- 
tioned using screen coordinates. This means the image may occupy a coordinate 
range of 0 to 479 horizontally, and 0 to 255 vertically. Because the GREDIT pro- 
gram uses some of this area for the legends and prompt messages, the usable image 
area is slightly less. The usable area is about 10 to 479 horizontally, and 30 to 
250 vertically. 


What is actually created and displayed by this program is a simple graphics 
data base. This graphics data base consists of a sequence of commands which 
specify how the image should be drawn. These commands will be referred to as 
"entries" in the data base. 


To enable you to create your image, three drawing functions are provided. 
These are move to a point, draw to a point, and print character string. An indi- 
vidual line is specified by moving to the starting point, then drawing to the end 
point. It is also possible to draw a line by drawing from the previous end point 
to a new end point. A character string is displayed at a desired point by first 
moving to that point and printing the character string. 


The GREDIT program has five types of data base entries to support the three 
drawing functions just described. There are two types of entries which perform the 
move function. The first is called a MOVE entry. In this entry, the point to move 
to is specified explicitly. The second is called an RMOVE entry. In this entry, 
the point to move to is specified relative to the previous end point. There are 
also two types of entries which perform the draw function. These are called DRAW 
and RDRAW entries. The draw entries will draw from the previous end point to the 
end point specified in the entry. In the DRAW entry, the end point is specified 
explicitly. In the RDRAW entry, the end point is specified relative to the start- 
ing point. The fifth entry performs the character string printing. This is called 
a LABEL entry. It will print the character string contained in the entry, starting 
at the previous end point. By using the appropriate combination of entries, almost 
any simple image can be created. 


The GREDIT program also has subshape capabilities. A subshape is a collection 
of entries which have been given a name. A subshape is most useful when a certain 
piece of an image appears in several places. You first define how this piece 
(i.e., subshape) is drawn and assign it a name. You then call for the subshape to 
be drawn at each of the desired locations. This saves entering the same sequence 
of entries more than once in the data base. 


There are two types of entries which support the subshape capability. The 
first is the SHAPE entry. This entry defines the name of the subshape whose en- 
tries appear in the data base immediately following the SHAPE entry. The SHAPE 
entry will contain the six character subshape name. The second type of subshape 
entry is the DRSHP entry. This is the entry which calls for a subshape to be 
diawn. The subshape will be drawn starting at the previous end point. 


For greater flexibility, the GREDIT program allows a subshape to call other 
subshapes (up to 20 levels deep). For example, a subshape called "BOX" may con- 
tain DRSHP entries for another subshape called "SQUARE". However, a subshape must 
not call itself, i.e., the "BOX" subshape must not contain a DRSHP BOX entry. 


There is one other type of entry supported, which is the END entry. This entry 
is found at the end of the entries for each subshape, and at the end of the data 
base. The END entries are controlled automatically by the GREDIT program. 


The GREDIT program organizes the data base into two parts. Starting at the 
beginning of the data base are all the subshape definitions and their entries. 
Following the subshape entries come the main drawing entries. This is where the 
entries which draw your image begin. When you call for the entire image to be 
draw, the GREDIT program will start drawing with the first main drawing entry. The 
subshape entries are placed before the main drawing entries to make the subshapes 
easier to find. 


For editing purposes, the GREDIT program maintains a current entry pointer. 
Many of the editing functions involve the current entry in some way. Also, during 
most of the editing fuctions a portion of the data base is displayed in the upper 
right corner of the display. This display will show the two entries preceeding the 
current entry (if they exist) , followed by the current entry, followed by the two 
entries after the current entry (if they exist). The current entry will always be 
indicated by an arrow. 


Entries are added to the data base using the INSERT menu. Entries will be in- 
serted just prior to the current entry. As each entry is inserted it is also drawn 
on the display. This allows you to see what you are inserting. Editing functions 
include DELETE and ADJUST. The DELETE function removes an entry or entire subshape 
from the data base. The ADJUST function allows you to adjust all appropriate en- 
tries by the same amount. 


To allow you to reposition the current entry pointer, there is a separate JUMP 
menu. You may jump to the entry at the beginning or end of the main drawing en- 
tries, or any subshape. You can also jump forward or backward in the data base a 
specified number of entries. You can also search for a point (FIND PNT function). 
The restriction is that this point must be the beginning point (i.e., the end point 
of the previous entry) of an entry. If found, the current entry pointer points to 
the next entry. There is also a DRAW menu to allow you to redraw the entire image 
or to redraw the image in increments. 


There are functions to load and save all or portions of the data base to and 
from disk. When saving, you may write all of the data base, all of the subshapes, 
or just selected subshapes to disk. When loading, you may load the entire data 
base, or just add the main drawing entries in the file on disk to those in the cur- 
rent data base. Finally there are disk functions and some general purpose func- 
tions, such as listing the subshape names. 


The functions provided should be sufficient to allow you to deal with simple 
gaphics images. The best way to learn how use GREDIT is through actual use. Refer 
to the following sections for details on the various functions in each of the 
menus. 


THE MENUS 


FIRST MAIN MENU 


In this menu the screen will contain axes across the top and left side of the 


screen. 


The small tic marks represent intervals of 5 pixels, and the larger marks 


represent 25 pixels. Also, the data base display is maintained in the upper right 


corner 
menu: 


LEGEND 
ADVANCE 
BACKWARD 


INSERT 


DELETE 


DRAW 


DEF SUB 


OTHER 


of the screen. The following choices of functions are presented in this 


FUNCTION 


Advance the current entry pointer to the next entry. 
Move the current entry pointer backward to the previous entry. 


Insert new entries between the previous entry and the current entry. 
See the INSERT MENU. 


Delete the current entry. The next entry will become the current 
entry. If the current entry is a SHAPE entry, the subshape and all its 
entries are deleted. 


Draw all or part of the data base. See DRAW MENU 


Adds a new subshape to the data base. You will be prompted for a 
subshape name which may be up to 6 characters long. A SHAPE entry will 
be placed in the data base at the end of all the subshape entries 
already present. An END entry is inserted along with the SHAPE entry 
to indicate the end of the entries for this subshape. The current 
entry pointer will point to this END entry so you may immediately use 
the INSERT command to put entries into this subshape. 


Move the current entry pointer by various amounts. See JUMP menu. 


Jumps the SECOND MAIN MENU. 


SECOND MAIN MENU 


This menu maintains the same display as in the FIRST MAIN MENU. In this menu, 
the SAVE, SAVE SUB, and LOAD functions will request a file name. If you wish to 
include a drive number in this file name, you must enclose the entire file name 
within double quotes. This is necessary to keep BASIC from interpreting the ":" as 
a terminator. The following functions are provided in this menu: 


LEGEND 


ADJUST 


LIST SUB 


SAVE 


SAVE SUB 


LOAD 


FUNCTION 


Adjusts MOVE, RMOVE, DRAW, and RDRAW type entries by a fixed amount. 
You will be asked to identify a point to be moved. Next you will be 
asked to identify where to move this point. Based on this input, a 
displacement is calculated. You will then be asked if you wish to 
adjust the current entry. You may respond by hitting "Y", "N", or "Q" 
keys to answer "YES", "NO", or "QUIT", respectively. If you answer 
with "Y", the displacement will be added to the coordinates of the 
current entry. After this entry is adjusted, succeeding entries will 
be drawn until the next MOVE, RMOVE, DRAW, or RDRAW entry is found or 
the end of the data base is encountered. This new entry is made the 
current entry and the data base entries are redisplayed. You will 
then be asked if you wish to adjust this new current entry. Responding 
with "N" performs the same as for "Y" except the entry is left as is. 
Responding with "Q" returns you to the SECOND MAIN MENU. 


Lists the names of all the subshape names in the data base. 


‘Saves the current graphics data base on disk. You will be asked to 


enter a file name. If the file specified already exists, you -will be 
prompted again for a file name. If the file does not exist, then all 
of the current data base is saved in this file. Answering with just a 
carriage return will return you to the SECOND MAIN MENU. 


Save subshape definitions to a data base disk file. You will first be 
asked to enter a file name. Next a message about the existence of the 
file is printed, and you are asked if you wish to save all the sub- 
shapes in the current data base. Enter "Y" to save all the subshapes 
in the current data base. Note that if the file already exists, then 
the subshapes will be appended to those in the file. This will over- 
write any main drawing entries that may be in the file leaving only 
subshapes in the file. The program returns to the menu when it is 
finished writing the subshapes. Enter "N" if you wish to save selected 
subshapes, or no subshapes. After entering "N", you will be asked to 
enter a subshape name. Entering a subshape name will cause that sub- 
shape definition to be written to the file. The program then prompts 
you for another subshape name. Answering with just a carriage return 
will return you to the SECOND MAIN MENU. 


Load a graphics data base file from disk. You will first be prompted 
to enter an existing file name. Answering with just a carriage return 
will return you to the SECOND MAIN MENU. If the file name entered does 
not exist, you will be prompted again for a file name. If the file 
does exist, it is assigned to CODOS channel 5. You will then be asked 
if you wish to load all of the data base or just the main drawing 
entries. Answer with "A" to load all the data base. The data base 
loaded will replace the current one. Answer with "M" to load just the 
main drawing entries. The entries loaded will be added to the end of 
the main drawing entries of the current data base. 


SECOND MAIN MENU (continued) 
LEGEND FUNCTION 
DISK CMD Jumps to DISK COMMANDS MENU. 
TO CODOS Returns to CODOS. 


EXIT Jumps back to the FIRST MAIN MENU. 


INSERT MENU 


When you enter the INSERT MENU, GREDIT determines if you are inserting into 
the main drawing commands or a SUBSHAPE. If you are inserting into a SUBSHAPE, you 
will be asked to enter a point from which to draw the SUBSHAPE. At this point the 
data base is drawn from the beginning of the SUBSHAPE up to but not including the 
current entry. If you are inserting into the main drawing commands, there will be 
a pause while a portion of the data base is redrawn. This is done so that the GRIN 
cursor will appear at the end point of the entry just prior to where entries will 
be inserted into the data base. Once this is done, the INSERT MENU is presented 
and the GRIN cursor is displayed. You may now insert as many entries as you like 
while in this menu. Each entry inserted will be drawn as it is entered keeping the 
image on the screen up to date. 


LEGEND FUNCTION 


MOVE Insert a MOVE entry into the data base. You should first’ position the 
’ GRIN cursor to the point you wish to move to, then press this key. 


DRAW Insert a DRAW entry into the data base. You should first position the 
GRIN cursor to the point you wish to draw to, then press this key. 


RMOVE Insert an RMOVE entry into the data base. You should first position 
the GRIN cursor to the point you wish to move to, then press this key. 


RDRAW Insert an RDRAW entry into the data base. You should first position 
the GRIN cursor to the point you wish to draw to, then press this key. 


DRAW SUB Insert a DRSHP entry into the data base. You will be prompted to enter 
a subshape name. If the subshape is defined it will be drawn upon in- 
sertion of this entry. Responding with just a carriage return will 
exit back to the INSERT MENU without inserting a DRSHP entry. The sub- 
shape will be drawn starting at the end point of the previous entry. 


Insert a LABEL entry into the data base. You will be prompted to enter 

LABEL a label string. This string may be up to 80 characters, which is all 
that will fit on one line. The string will be drawn starting at the 
end point of the previous entry. 


Draw the current entry and advance the current entry pointer to the 
ADVANCE next entry. 


Jump back to FIRST MAIN MENU. 
EXIT 


DRAW MENU 


When you first enter the DRAW MENU, GREDIT will determine if the current entry 
pointer is pointing into the main drawing commands ora subshape. If it isa 
subshape, you will be prompted to enter a point from which to draw the subshape. 
The DRAW MENU then presents the following functions for drawing all or part of the 
main drawing commands or subshape: 


LEGEND FUNCTION 
ALL Draws all of the subshape or main drawing commands after first clearing 


the screen. y 


FROM BEG Draws from the beginning of the subshape or main drawing commands up to 
but not including the current entry. 


DRAW 10 Draw the next 10 entries. Drawing a subshape counts as one entry. 

DRAW 5 Draw the next 5 entries. Drawing a subshape counts as one entry. 

DRAW 1 Draw the next entry. 

STEP Draws the current entry and advances the current entry pointer to the 
next entry. 


SAVE IMG Saves the screen image to the printer or disk file. You will be asked 
to select to save the image to the printer or disk file. Entering "P" 
prints a copy of the image on the screen to the printer. For this to 
work you must have a copy of SPRINT.Z on the disk in drive 0. Entering 
"F" will save the image as a memory save to a CODOS file. In this 
case, you will be asked for a file name. Responding with just a car- 
riage return will return you to the DRAW menu without saving the image. 
Responding with a key other than "P" or "F" to the first prompt will 
also return you to the DRAW menu. 


Jumps back to the FIRST MAIN MENU. 


EXIT 


JUMP MENU 


The JUMP MENU presents the following functions to allow you to reposition the 
current entry pointer in various ways: 


LEGEND 
TO BEG 


TO END 


TO SUB 


TO S END 


FIND PNT 


FORWARD 
BACKWARD 


EXIT 


FUNCTION 
Sets the current entry pointer to the first main drawing entry. 


Sets the current entry pointer to the end of the main drawing entry. 


Sets the current entry pointer to the first drawing entry in a sub- 
shape. 


Sets the current entry pointer to the end of the drawing entries ina 
subshape. 


Finds where a specified beginning point occurs in the data base. You 
will be asked to enter the point to search for. This point should be 
the beginning point of one of the entries in the data base. The search 
will begin with the current entry. 


The search is accomplished by drawing (or redrawing) entries one at a 
time, checking the beginning point of each entry before it is drawn. 
If a match is found the searching stops. The current entry will be 
this entry. At this point the data base will be displayed and you will 
be asked if this is the desired entry. If so, enter Y for "yes". If 
not, enter N for "no", and searching will resume. You may also enter Q 
for "quit", if you wish to stop the search at this point. Searching 
will stop and the query given no matter where the match occurs. The 
match may be within a subshape. 


The search must begin with the current entry pointer pointing in the 
main drawing entries. It cannot start within a subshape, though it may 
stop within a subshape. If a match is not found when the end of the 
data base is reached, the current entry pointer is reset to the begin- 
ning of the main drawing entries. 

Move the current entry pointer forward a specified number of entries. 
Move the current entry pointer backward a specified number of entries. 


Jump back to FIRST MAIN MENU. 


LEGEND 
OPEN 0 

OPEN 1 

CLOSE 0 
CLOSE 1 
FILES 0 
FILES 1 


DELETE 


EXIT 


DISK COMMANDS MENU 
FUNCTION 
Opens drive 0. 
Opens drive 1. 
Closes drive 0. 
Closes drive 1. 
Clears the screen and executes a "FILES 0" command. 
Clears the screen and executes a "FILES 1" command. 
Deletes a file. You will be prompted to enter a file name to be 
deleted. If this file name is to include a drive number, it must be 
enclosed within double quotes. Otherwise the ":" will be interpreted 


as a terminator and the drive number will be ignored. 


Jumps back to the SECOND MAIN MENU. 


THE DATA BASE FORMAT 


The following is a description of the format of the data base as it is found 
in memory and on disk. This should prove useful if you wish to make enhancements 
to the GREDIT program or put the data base to other uses. 


Under BASIC, the entire data base is stored in the integer array DD%(). The 
data base consists of drawing entries, which are divided into two sections. These 
are the subshape section and main drawing entries section. The two sections are 
stored in the array DD%() as follows. 


DD4(0) - pointer to the first main drawing entry. 
DD%(1) to DD%4(DD%(0)-1) - The subshape entries. 
DD%(DD%(0)) to DD4(PE-1) - The main drawing entries 


where PE is a pointer to the first array element beyond the END entry at the end of 
the data base. If the data base contains no subshapes, then DD%(0) will contain 1 
and DD4(1) will contain the first main drawing entry. 


There are seven different drawing entries. These entries are MOVE, DRAW, 
RMOVE, RDRAW, DEFINE SUBSHAPE, DRAW SUBSHAPE, and LABEL. The format for these in 
the data base is shown below for an entry starting at DD%(I): 


MOVE Entry DD4(I) = 1 for MOVE, = 2 for DRAW 
and DD4(I+1) = X coordinate 
DRAW Entry DD4(I+2) = Y coordinate 

DD%(I+3) = Length of entry = 4 


RMOVE Entry DD4(I) 3 for RMOVE, = 4 for RDRAW 


and DD4(I+1) = Relative X coordinate 
RDRAW Entry DD4(I+2) = Relative Y coordinate 
DD%(I+3) = Length of entry = 4 
DEFINE DD4(I) 25 
SUBSHAPE DD4(I+1) = Length of subshape 
Entry DD4(I+2) = Subshape name 
to 1 character per array element 
DD4(I+7) 
DD%(I+8) = Length of entry = 9 
DRAW DD4(I) = 6 
SUBSHAPE DD4(I+1) = Name of subshape to draw 


Entry to 1 character per array element 
DD4(I+6) 
DD%(I+7) = Length of entry = 8 


LABEL Entry DD4(I) vA 


DD4(I+1) = Length of entry = L+3 

DD4(I+2) = Characters of label 

to 1 character per array element 
DDS(I+L) L = number of characters in the label 


DD4(I+L+1) = Length of entry = L+3 
The format for the END entry is: 


END Entry DD4(I) 20 
DD4(I+1) = Length of entry = 2 


10 


A data base file on disk contains a memory image copy of the data base in 
DD%(). This copy of the array DD%() is preceeded by an integer (i.e. two byte 
signed representation) containing the number of integers in the rest of the file. 
This integer is actually the quantity PE for the data base in the file. Because it 
is a copy of the DD4%() array, the second integer in the file (i.e. the one follow- 
ing the count) is equivalent to DD%#(0). The next integer is equivalent to DD%(1), 
etc. 


Because all the numbers in the data base are BASIC integers (i.e. two byte 
signed quantities), it is not difficult for another BASIC or machine language 
program to access a data base file on disk. To read a data base file using BASIC 
and the CIL, the following command may be used: 


SYSTEM "ASSIGN 5 YOURDB.D":BLKRD@ 5,PE%,DD%(0) TO DD%(PE%-1):SYSTEM "FREE 5" 
Because of the way BASIC handles numbers, the most significant byte of each 


integer preceeds the least significant byte in the file. This is especially 
important if you are accessing the file from machine language. 


